COMMENT ⊗   VALID 00014 PAGES
C REC  PAGE   DESCRIPTION
C00001 00001
C00002 00002			General PUB Macros in GENRAL.PUB[SUB,SYS]
C00005 00003			Output Device
C00006 00004			Fonts and Special Characters
C00012 00005			Sides of the Page to Be Printed
C00014 00006			Width of Left Margin
C00016 00007			Slurping Up the Macros File
C00017 00008			Columns per Side to Be Printed
C00019 00009			Spacing
C00020 00010			Section Headings
C00024 00011			Text Justification
C00026 00012			Footnotes
C00028 00013			Automatic Generation of Table of Contents
C00030 00014			Example
C00032 ENDMK
C⊗;
		General PUB Macros in GENRAL.PUB[SUB,SYS]
			Version 1.2, 15 October 1979
			     Brian P. McCune

GENRAL.PUB[SUB,SYS] sets up some standardized PUB conventions for
producing documents.  These macros are designed for two different user
groups.  The first consists of casual PUB users who desire to avoid having
to learn much about PUB.  The price you pay for being in this group is
that you have to live with the features and document formats that are
provided.  The second group is that of PUB hackers.  By copying these
macros to your own disk area, these macros provide a starting place for
the venturesome souls who want to tailor them to their own needs.

The features provided by these macros include use of either XGP or LPT as
output device; lightface, italic, and boldface Baskerville fonts with all
keyboard characters of Stanford ASCII available; formats for printing on
either one or both sides of a page; formats for printing with either a 1"
or 1.5" left margin on each page; formats for printing one or two columns
per side; single, double, triple, or even greater spacing; macros for four
levels of section headings; footnote generation; and automatic generation
of table of contents.  Follow the instructions below to properly set up
your .PUB file to get the desired options.  Especially note the example at
the end of this file.

See "PUB:  The Document Compiler" (in PUB.TES[S,DOC]) and the "PUB Update"
(in PUB.UPD[S,DOC]) for the details of PUB.
		Output Device

Using the appropriate command of

	.DEVICE XGP;
	.DEVICE LPT;

choose the desired output device.  XGP is highly recommended; however,
note that LPT is useful if you want a document which is both printable and
readable online and one which can be printed at sites not possessing an
XGP.
		Fonts and Special Characters

The following paragraph is in effect only if the device type is XGP.  Font
1 is defined to be lightface Baskerville; Font 2, italic Baskerville; Font
3, boldface Baskerville; Font 4, FIX25 for the special characters not
available in Baskerville; and Font 5, SUP for footnote numbers.  You are
started out in lightface Baskerville.  All of the Baskerville ligatures
are provided automatically.  All of the Baskerville fonts provide access
to all of the Stanford ASCII characters which can be typed in from a
Stanford keyboard.  (The characters "hidden" beneath NULL, TAB, LF, VT,
FF, CR, ALT, and BS are unavailable.) Note that logical not ("¬") will
print as such; type two consecutive hyphens ("--") to get a dash.  Alpha
("α") and percent sign ("%") are turned on as PUB response characters to
provide for quoting characters and changing fonts, respectively.  Please
do not turn off alpha; if you need an alpha in your text, quote it ("αα").
Surrounding a section of text with the appropriate delimiters will cause
it to be printed in //italics/ or ⊗⊗boldface⊗.  Note that you can't get an
italic slash or boldface circle times if you use this scheme; switch fonts
by using percent sign instead.  Also, a double quote in italics or
boldface must be doubled (`""').  After the special font is over, you are
returned to the font that you were in upon entry.  Thus, you can switch to
italic or boldface from any different font.  But, please, no recursion!  A
pair of double quotes is converted into a pair of matching Baskerville
open double quote and close double quote.  If you want exactly one double
quote (e.g., as an abbreviation for inches), you must type `α"'.  Note
that nested pairs of double quotes won't work; use single quotes on the
second level and don't go any deeper than that.  The following characters
should be input as shown:

	to get						input
	α						αα
	%						α%
	" (unmatched)					α"
	dash						--
	//						/α/
	⊗⊗						⊗α⊗
	circumflex (lightface only)			αε
	period with extra space (lightface only)	α∀
	" (italic and boldface only)			""
	" (unmatched, italic and boldface only)		α""

The following paragraph is in effect only if the device is LPT.  If the
device type is LPT, too bad!  You only get LPT font for starters.  Alpha
("α") and the underline command characters ("↓_" and "_↓") are turned on.
The font switching character ("%") is turned on so that if you have font
switches in a document that was originally done on the XGP, they will act
as no-ops and be swallowed up.  Instead of italic type, you get things
//underlined/.  Note that you can't get an underlined slash using this
scheme; use ↓_text with slash_↓ instead.  Instead of boldface, you get
⊗⊗all capital letters⊗.  You can't get an underbar or circle times within
all capitals however, so exit all capitals mode for one character instead.
Also, a double quote in underline or all capitals mode must be doubled.
Underline and all capitals modes even work simultaneously.  The following
characters should be input as shown:

	to get						input
	α						αα
	%						α%
	↓						α↓
	//						/α/
	⊗⊗						⊗α⊗
	" (underline and all capitals only)		""
		Sides of the Page to Be Printed

Using the appropriate statement of

	.SIDES ← 1;
	.SIDES ← 2;

choose whether printing will be on one side of a page or both sides.  For
documents that will be printed on only one side of the paper, the section
name of the current section will appear in the upper left of each page and
the current page number in the upper right.  For documents that will be
printed on both sides of the paper, even numbered (lefthand) pages will
have the page number in the upper left corner and the section name in the
upper right.  Odd numbered (righthand) pages will have the subsection name
(if any) in the upper left and the page number in upper right.  All page
headings are printed in boldface Baskerville (but not in all capitals on
LPT).
		Width of Left Margin

By using the appropriate statement of

	.MARGIN ← "NARROW";
	.MARGIN ← "WIDE";

you will get either a narrow (i.e., 1") or wide (i.e., 1.5") left margin
on each page.  The other margins are unaffected (i.e., left at 1").
Narrow margins are appropriate for an unbound document, e.g., one that is
left as loose pages or stapled.  Wide margins are necessary for a document
that is going to be bound by any technique that gobbles up much of the
margin, e.g., Velo, spiral, or perfect.  You probably want wide margins
for an AI Memo or CS Report.  And they are required for Ph.D. theses.

Caution:  The wide margin option for device LPT has the effect of making
the RIGHT margin 1.5" rather than the left!
		Slurping Up the Macros File

Following the DEVICE and SIDES statements (discussed above), there must be
a statement of the form

	.REQUIRE "GENRAL.PUB[SUB,SYS]" SOURCE_FILE;

All macro calls discussed below must occur after this REQUIRE statement.
		Columns per Side to Be Printed

By using the appropriate command of

	.COLMNS 1;
	.COLMNS 2;

printing will be done in either one column or two.  In either case the
top, bottom, left, and right margins are all one inch, unless the "WIDE"
margin option has been selected, in which case the left margins are 1.5
inches.  With two columns there is a one-half inch space between the
columns.  In addition, in the middle of your text you can switch to one or
two column printing by using the appropriate command; however, this will
start a new page.  If there is a table of contents, it will be in the
column format specified by the last COLMNS command given.
		Spacing

By using the command

	.SPACES <positive integer>;

you will get single, double, triple, etc.  spacing (i.e., 1 gives single
spacing, 2 double spacing, etc.).  Spacing can be changed throughout a
document, but such a change causes a paragraph break.  Initially single
spacing is assumed.  If there is a table of contents, it will be spaced
according to the last SPACES command given.
		Section Headings

Main sections and appendices can either start a new page (an odd page if
printing two sides) by using

	.NEW_PAGE_ON_SECTION TRUE;

or not start a new page by using

	.NEW_PAGE_ON_SECTION FALSE;

If the latter mode is in effect, then at least five lines of text will
follow the section heading in the same column.  Initially a new section
will start a new page.

Begin each logical segment of your document with the appropriate one of
the following macros:

	.S |<section name>|;
	.APP |<appendix name>|;
	.SS |<subsection name>|;
	.SSS |<subsubsection name>|;

None of these section names should contain a vertical bar ("|"), left
curly bracket ("{"), left arrow ("←"), or right arrow ("→").  Sections
will be numbered one up.  Appendices are labelled with capital letters,
beginning with "A".  Subsections and subsubsections will be numbered
decimally within the section or appendix (e.g., 1.1.1 or A.1.1).  All
three main section or appendix levels will appear in the table of contents
if there is one (see below).  All section and appendix headings will
appear in boldface Baskerville (all capitals for LPT).  At least four
lines of text will occur below a subsection name in the same column; at
least three lines are guaranteed for subsubsections.

If you wish to have an unnumbered section which will not appear in the
table of contents, use the following macro to make its title appear
centered and in boldface Baskerville (all capitals for LPT):

	.CB |<title>|;

The same conventions as for section names hold for this title.  CB
guarantees that at least two lines of text occur below the title in the
same column.

None of the line guarantees specified in this section are in effect within
a column containing footnotes.  If you end up with a widow section
heading, put a GROUP command just before the heading and an APART command
just after the first paragraph following the heading.
		Text Justification

Another handy macro is

	.JUSTIFY;

which begins standard text justification.  Just before entering your text
file JUSTIFY is called, so you will only need to call it if you ever stop
justifying for some reason.

Note that this macro RETAINs all blanks between words in order to allow
for two blanks after sentences ending with a period, question mark,
exclamation mark, colon, right parenthesis, right bracket, right single
quote, double quote, etc.  In order for this to work correctly, you must
always leave the exact number of blanks that you want to appear in the
justified text.  Unwanted blanks (often caused by fixed width
justification such as exhibited in this paragraph) can be removed by using
the ETV extended command JFILL.
		Footnotes

A footnote that will appear at the bottom of the current column can be
generated at the point of reference.  This is done by a call of the form

	∪∪<text of footnote>∪

Because of this format, you can't use a "∪" character inside a footnote.

Footnotes are numbered one up within each main section.  The above call is
replaced by the next footnote number generated, displayed as a superscript
numeral (a numeral in brackets on LPT).  The footnotes for a column will
appear sequentially at the bottom of that column, separated from the main
text by a solid line of underbars.  The footnote entry consists of the
footnote number followed by the text of the footnote.  The text is
displayed single spaced, in lightface Baskerville font, and justified.

Caution: The handling of footnotes by PUB is known to be buggy, so be
prepared to fiddle a bit to get them to work.
		Automatic Generation of Table of Contents

If you wish to have a table of contents, put the PUB statement

	.INSERT CONTENTS;

before the REQUIRE statement discussed above and call the macro

	.COLLECT CONTENTS;

at the very end of your document.  Note that the column format and spacing
of the table of contents are determined by the last call to COLMNS and
SPACES, respectively.  Currently calling COLMNS immediately before COLLECT
CONTENTS doesn't work quite right, so be sure to have some text in
between.  Each page of the table of contents has "Table of Contents" in
boldface centered at the top and the page number in lowercase Roman
numerals centered at the bottom.
		Example

Here is an example of using these commands.  The text of the paper in this
case is located in TEST.TXT.  A two sided, two column document with a 1.5"
left margin will be produced for the XGP.  Using the optional commands in
curly brackets will override the default conditions, producing a table of
contents, a double spaced document, and no new page at the start of main
sections and appendices.

	.DEVICE XGP;
	.SIDES ← 2;
	.MARGIN ← "WIDE";
       {.INSERT CONTENTS;}
	.REQUIRE "GENRAL.PUB[SUB,SYS]" SOURCE_FILE;
	.COLMNS 2;
       {.SPACES 2;}
       {.NEW_PAGE_ON_SECTION FALSE;}
	.REQUIRE "TEST.TXT" SOURCE_FILE;
       {.COLLECT CONTENTS;}

If the file containing the above statements is called TEST.PUB, then you
should call PUB with the monitor command

	.PUB TEST